# golimiter API Documentation

## `TokenBucket`

TokenBucket represents a rate limiting mechanism based on the token bucket algorithm.

### Fields

- `capacity` (`int`): Maximum number of tokens the bucket can hold.
- `tokens` (`int`): Current number of tokens in the bucket.
- `fillRate` (`int`): Rate at which tokens are added to the bucket (tokens per second).
- `lastTimestamp` (`time.Time`): Timestamp of the last token retrieval or addition.
- `expirationTime` (`time.Time`): Time when the bucket will expire and be removed from the manager.
- `mu` (`sync.Mutex`): Mutex for synchronization.

### Constructor

#### `NewTokenBucket`

```go
func NewTokenBucket(capacity, fillRate int, bucketLifetime time.Duration) *TokenBucket
```

Creates a new TokenBucket instance with the specified parameters.

- `capacity` (`int`): Maximum number of tokens the bucket can hold.
- `fillRate` (`int`): Rate at which tokens are added to the bucket (tokens per second).
- `bucketLifetime` (`time.Duration`): Duration for which the bucket will be valid.

Returns a pointer to the created TokenBucket.

### Method

#### `TakeToken`

```go
func (tb *TokenBucket) TakeToken() bool
```

Tries to retrieve a token from the bucket. Returns `true` if successful, `false` otherwise.

## `TokenBucketManager`

TokenBucketManager manages multiple token buckets.

### Fields

- `tokenBuckets` (`map[string]*TokenBucket`): Map of IP addresses to their corresponding token buckets.
- `mu` (`sync.Mutex`): Mutex for synchronization.

### Constructor

#### `NewTokenBucketManager`

```go
func NewTokenBucketManager() *TokenBucketManager
```

Creates a new TokenBucketManager instance.

Returns a pointer to the created TokenBucketManager.

### Methods

#### `GetTokenBucket`

```go
func (tm *TokenBucketManager) GetTokenBucket(ip string) *TokenBucket
```

Retrieves the `TokenBucket` associated with the provided IP address. If no bucket exists, it returns `nil`.

- `ip` (`string`): IP address for which the token bucket is requested.

#### `CreateTokenBucket`

```go
func (tm *TokenBucketManager) CreateTokenBucket(ip string, capacity, fillRate int, bucketLifetime time.Duration) (*TokenBucket, error)
```

Creates a new `TokenBucket` for the given IP address and stores it in the manager.

- `ip` (`string`): IP address for which the token bucket is requested.
- `capacity` (`int`): Maximum number of tokens the bucket can hold.
- `fillRate` (`int`): Rate at which tokens are added to the bucket (tokens per second).
- `bucketLifetime` (`time.Duration`): Duration for which the bucket will be valid.

Returns a pointer to the created `TokenBucket` or an error if a bucket already exists for the given IP.

#### `cleanupExpiredTokenBuckets`

```go
func (tm *TokenBucketManager) cleanupExpiredTokenBuckets()
```

Removes expired token buckets from the manager.

This method iterates through the stored token buckets and removes those that have expired based on their `expirationTime` field.

#### `StartCleanupTask`

```go
func (tm *TokenBucketManager) StartCleanupTask(cleanupInterval time.Duration)
```

Initiates a periodic task to clean up expired token buckets at the specified interval.

- `cleanupInterval` (`time.Duration`): The time interval between cleanup task executions.
